<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8"/>
    <title>Concepts</title>
    <link rel="stylesheet nofollow" type="text/css" href="http://code.google.com/css/codesite.css"/>
    <link rel="stylesheet nofollow" type="text/css" href="../../util/docs/template/local_extensions.css"/>
    <script type="text/javascript" src="http://code.google.com/js/prettify.js"></script>
  </head>
  <body onload="prettyPrint()">
<div>
<a name="Top"></a>  
<h1>ArcGIS Server Link for Google Maps API: Concepts</h1>
<p><b>
  <a href="examples.html">Examples</a>
  | <a href="reference.html">Class References</a>
  </b></p>
<p>This library provides access to ESRI's ArcGIS Server via it's  
     <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/'> 
     REST API</a> from 
     <a href='http://code.google.com/apis/maps/documentation/reference.html'>Google Maps API</a>.
     The main concepts of this library are:
     <ul>
       <li>Broader Spatial Reference Support. It works with ALL ArcGIS Server services
        (v9.3 with REST enabled, square tiles if cached), not just those published in "Web Mercator".</li>
       <li>Two tier object model. It contains a set of classes that strictly follow
         the class design style and convention of the core GMap API, 
        plus a set of classes that modeled closely to the REST Service resources and operations.</li>
     </ul>
     </p>
 </div>
<div>
  <h2><a name="GMaps"></a>Google Maps API Extension Classes</h2> 
<p>For developers who are familiar with the core Google Maps API classes, 
this library can be considered as a collection of custom/extension 
classes to the core API that facilitates access to ArcGIS Server. 
You can accomplish many tasks by using only those subclasses. 
Several principles are used in the design:
</p>
<ul>
  <li>Use object literals in constructors as options.</li> 
  <li>Use callback function in methods, not in constructors</li> 
  <li>Use events to identify key steps in operations</li>
</ul> 
 <p>The following table describes the classes in the core Google Maps API and their corresponding 
sub classes in this library. </p>
<table>
  <tr>
    <th>Core Google Maps API Class</th>
    <th>ArcGIS Link Class</th>
  </tr>
  <tr>
    <td>
    <a href='http://code.google.com/apis/maps/documentation/reference.html#GOverlay'>GOverlay</a>,
    <a href='http://code.google.com/apis/maps/documentation/reference.html#GGroundOverlay'>GGroundOverlay</a>
    </td>
    <td>
     <a href='reference.html#ArcGISMapOverlay'>ArcGISMapOverlay</a>  
    </td>
  </tr>
  <tr>
    <td>
    <a href='http://code.google.com/apis/maps/documentation/reference.html#GTileLayer'>GTileLayer</a>  
    </td>
    <td>
     <a href='reference.html#ArcGISTileLayer'>ArcGISTileLayer</a>  
    </td>
  </tr>
  <tr>
    <td>
    <a href='http://code.google.com/apis/maps/documentation/reference.html#GTileLayerOverlay'>GTileLayerOverlay</a>  
    </td>
    <td>
     <a href='reference.html#ArcGISTileLayerOverlay'>ArcGISTileLayerOverlay</a>  
    </td>
  </tr>
  <tr>
    <td>
    <a href='http://code.google.com/apis/maps/documentation/reference.html#GMapType'>GMapType</a>
    </td>
    <td>
     <a href='reference.html#ArcGISMapType'>ArcGISMapType</a>  
    </td>
  </tr>
   <tr>
    <td>
    <a href='http://code.google.com/apis/maps/documentation/reference.html#GProjection'>GProjection</a>
    </td>
    <td>
     <a href='reference.html#ArcGISProjection'>ArcGISProjection</a>  
    </td>
  </tr>
</table>
</div>
<div>
<h2><a name="Rest"></a>REST API Classes</h2> 
<p>The GMap extension classes are built on top of a number of classes that
communicates with ArcGIS Server. Developers who want to get lower level access can
use those classes by calling the <code>ArcGISTileLayer.getMapService()</code>
 or <code>ArcGISMapOverlay.getMapService()</code>. Those classes are designed to 
 closely reflect the actual <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/'> REST API</a>. 
 Several principles are used in the design:
</p>
<ul>
  <li>Each service/resource is a class with constructor</li> 
  <li>Operations performed on resource are methods of the resource classes.</li>
  <li>Use object literals whenever possible such as parameters and results</li> 
</ul> 
<p>The following is a table that describes the REST resource and their corresponding classes:</p>
<table>
  <tr>
    <th>REST Resource</th>
    <th>Library Class</th>
  </tr>
  <tr>
    <td>
    <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/mapserver.html'>Map Service</a>
    </td>
    <td>
     <a href='reference.html#ArcGISMapService'>ArcGISMapService</a>  
    </td>
  </tr>
  <tr>
    <td>
    <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/layer.html'>Layer</a>
    </td>
    <td>
     <a href='reference.html#ArcGISLayer'>ArcGISLayer</a>  
    </td>
  </tr>
  <tr>
    <td>
    <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/geocodeserver.html'>Geocode Service</a>
    </td>
    <td>
     <a href='reference.html#ArcGISGeocodeService'>ArcGISGeocodeService</a>   
    </td>
  </tr>
  <tr>
    <td>
    <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/gpserver.html'>GP Service</a>
    </td>
    <td>
     TBD
    </td>
  </tr>
  <tr>
    <td>
    <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/geometryserver.html'>Geometry Service</a>
    </td>
    <td>
     <a href="reference.html#ArcGISGeometryService">ArcGISGeometryService</a>
    </td>
  </tr>
   <tr>
    <td>
    <a href='http://resources.esri.com/help/9.3/arcgisserver/apis/rest/imageserver.html'>Image Service</a>
    </td>
    <td>
     TBD
    </td>
  </tr>
</table>
</div>
<div>
<h2><a name="Load"></a>The load Event</h2> 
<p>ArcGIS services may be published with different spatial reference systems. 
If they are pre-rendered as map tiles, they will use a certain "tiling scheme". 
Some of them may use the exact same tile scheme as Google maps, some may not.
In order to let the core Google Maps API know how to load tiles correctly, 
it is necessary to get information about how the tiles are constructed from the server first. 
 This is an asynchronous process. For this reason, it's often necessary to wait
 for the "load" event before using an ArcGIS Link class.
 It is not necessary to wait if... 
<ul><li>The resource is added as 
an <a href="reference.html#ArcGISMapOverlay">ArcGISMapOverlay</a>  </li>
<li>The tiles are created with the same tile system as Google Maps, in ArcGIS's
terms, "cached with Web-Mercator scheme";
</li>
<li>You pass in an <a href="reference.html#ArcGISProjection">ArcGISProjection</a> to the constructor of 
 <a href="reference.html#ArcGISTileLayer">ArcGISTileLayer</a> so the API immediately knows how to request tiles;
</li>
</ul> 
<p>Rule of thumb: when in doubt, always use 'load' event. </p>
<pre>
var tileLayer=new ArcGISTileLayer(url);
GEvent.addListener(tileLayer,'load', function(){
  // start use the tile Layer.
});
</pre> 
</p>
</div>
<div>
<h2><a name="SR"></a>Spatial Reference Support</h2> 
<p>This library provides additional spatial reference support by implementing interface
 <a href="reference.html#ArcGISSpatialReference">ArcGISSpatialReference</a>, which converts between 
 Lat/Lng and map coordinates, then using an intermediate class  
 <a href="reference.html#ArcGISProjection">ArcGISProjection</a> to bridge Google's 
 coordinate system to ArcGIS's system. This library includes a few built-in spatial references:
 WGS84 (4326) and WebMercator (102113). It also has two of the most widely used projections: 
LambertConformalConic and Transverse Mercator. Spatial references based on these
two projections can be used by calling <code>ArcGISSpatialReferences.addSpatialReference(wkid, wkt)</code>. 
A developer can also implement their own projection class and plug it in. 
If the system fails to find an implemented spatial reference, it will use 
<a href="reference.html#ArcGISFlatSpatialReference">ArcGISFlatSpatialReference</a> 
for somewhat less accurate coordinates transformation. Here is a summary of options:
  <ul>
    <li>If you use map service as <a href="reference.html#ArcGISMapOverlay">ArcGISMapOverlay</a>
     and add on top of backgrounds, no special action is necessary.
     You can simply use 
     <pre>
gmap.addOverlay(new ArcGISMapOverlay(url));
     </pre>
     </li>
    <li> If you use a tiled map service, and you know it was created using the same coordinate system
    Google Maps uses (WebMercator in ArcGIS), no special action is necessary.
     You can simply use
      <pre>
gmap.addMapType(new ArcGISMapType(url));
      </pre>.
       
     </li>
     <li> If you use a tiled map service, and you know it was created using ArcGIS Online tiling scheme, or
     it's real spatial reference code is 4326(WGS84) or 4269 (NAD83), you should use it after the "load" event.
     <pre>
var maptype=new ArcGISMapType(url);
GEvent.addListener(maptype, 'load', function(){
  gmap.addMapType(maptype);
});
      </pre>.
     </li>
     <li> If you use a tiled map service, and you know it's spatial reference was based on Lambert Conformal Conic
      or Transverse Mercator projection (as most State Plane Coordinate System do), you should find it's Well-known-Text
      value from  <a target=esri href='http://edndoc.esri.com/arcims/9.2/elements/pcs.htm'>
ESRI documentation</a> and add it into the application, then use it after the "load" event.
     <pre>
ArcGISSpatialReferences.addSpatialReference(2264, 'PROJCS["NAD_1983_StatePlane_North_Carolina_FIPS_3200_Feet",......');
var maptype=new ArcGISMapType(url);
GEvent.addListener(maptype, 'load', function(){
  gmap.addMapType(maptype);
});
      </pre>.
     </li>
     <li> If you use a tiled map service, but you just want to quickly use the service, and
     you do not need a precise Lat Lng to real coordinate transformation, you can simply use it after the "load" event. 
     The API will use 
     <a href="reference.html#ArcGISFlatSpatialReference">ArcGISFlatSpatialReference</a>. 
     <pre>
var maptype=new ArcGISMapType(url);
  GEvent.addListener(maptype, 'load', function(){
  gmap.addMapType(maptype);
});
      </pre>.
     </li>
     <li> Finally, if you use a tiled map service, but it's spatial reference was not based on LCC or Transverse Mercator, and
     you DO need a precise Lat Lng to real coordinate transformation, you can implement your own  
     <a href="reference.html#ArcGISSpatialReference">ArcGISSpatialReference</a> class, add it to application, 
     then use it after the "load" event.
     <pre>
function MySpatialReference=function(params){...}
MySpatialReference.prototype.reverse=function(coordsArray){...return [lng,lat]};
MySpatialReference.prototype.forward=function(lnglatArray){...return [x,y]};
MySpatialReference.prototype.getWrapWidth=function(){...};
ArcGISSpatialReferences.addSpatialReference(myWkid,new MySpatialReference({...}));
var maptype=new ArcGISMapType(url);
GEvent.addListener(maptype, 'load', function(){
  gmap.addMapType(maptype);
});
      </pre>.
     </li>
  </ul>

</p>
</div>
<div>
<h2><a name="Order"></a>Layer Orders/z-Index</h2> 
<p>
  ArcGIS Maps can be added with one of the following types: <a href="reference.html#ArcGISMapOverlay">ArcGISMapOverlay</a>,
  <a href="reference.html#ArcGISTileLayerOverlay">ArcGISTileLayerOverlay</a>, or <a href="reference.html#ArcGISMapType">ArcGISMapType</a>.
  <ul><li><code>ArcGISMapOverlay</code> is best suited for dynamic map service in which 
  sub layers can be turned on/off and map images will be generated on the fly.
   They should be on top of map resources.
  They are added to the <code>G_MAP_OVERLAY_LAYER_PANE</code>.
  </li>
  <li><code>ArcGISTileLayerOverlay</code> is best suited for some common shared service that maybe
  used in different background context. They are below <code>ArcGISMapOverlay</code> but on top of
  the <code>ArcGISTileLayer</code>s inside the MapTypes. They are in <code>G_MAP_OVERLAY_LAYER_PANE</code>.
  </li>
  <li>The order of <code>ArcGISMapOverlay</code> and <code>ArcGISTileLayerOverlay</code> depends on the order they were added to Map.
  The one added later will be on top of the one added earlier.
  </li>
  <li><code>ArcGISMapType</code> is best suited for specialized background map. It consists of one or 
  more <code>ArcGISTileLayer</code> and should stay at the bottom of the stack.
  They are in <code>G_MAP_MAP_PANE</code>.
  </li>
  </ul>
  
</p>
</div>

<p></p>
<p><hr/></p>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
var pageTracker = _gat._getTracker("UA-3946449-5");
pageTracker._trackPageview();
</script>
</body>
</html>
